/***************************************************************
 *  Copyright (c) 2007 by GroupMe! Team (www.groupme.net)
 *  All rights reserved
 *
 *  This file is part of the GroupMe! Project. You can utilize
 *  software of the GroupMe! project under the terms of the 
 *  GNU Lesser General Public License as published by the
 *  Free Software Foundation in version 2.1.
 * 
 *  The GNU Lesser General Public License can be found at:
 *  http://www.gnu.org/licenses/lgpl.html
 *
 *  This copyright notice MUST APPEAR in all copies of the file!
 ***************************************************************/
package net.groupme.model;

import java.util.Collection;

import net.groupme.exceptions.DeleteFailedException;
import net.groupme.exceptions.GroupVisualizationException;
import net.groupme.exceptions.InsertFailedException;

/**
 * This interface defines a Group object in the GroupMe! project. A Group
 * represents a collection of Resources ({@link net.groupme.model.Resource}
 * which can be visualized by different GroupVisualizations
 * {@link net.groupme.model.GroupVisualization} and can be used by different
 * Users ({@link net.groupme.model.User} with different roles. It also can be
 * tagged {@link net.groupme.model.Tag}.
 * 
 * created on 15.04.2007
 * 
 * @author Mischa Frank <a
 *         href="mailto:code@planetfrank.net">code@planetfrank.net</a>
 * @author Patrick Siehndel <a
 *         href="mailto:patrick.siehndel@gmx.de">patrick.siehndel@gmx.de</a>
 * @author Fabian Abel, <a href="mailto:abel@l3s.de">abel@l3s.de</a>
 * 
 * @author last edited by: $Author: fabian $
 * 
 * @version $Revision: 1.4 $ $Date: 2008-06-12 12:17:16 $
 * 
 */

public interface Group extends Resource {

	/**
	 * This method adds a resource to the group.
	 * 
	 * @param resource
	 * @throws InsertFailedException
	 */
	public void addResource(Resource resource) throws InsertFailedException;

	/**
	 * This method adds a user with a role to the group.
	 * 
	 * @param role
	 * @param user
	 * @throws InsertFailedException
	 */
	public void addUser(String role, User user) throws InsertFailedException;

	/**
	 * This method adds a visualization for the group for a given user.
	 * 
	 * @param groupVisualization
	 * @param user
	 * @throws InsertFailedException
	 */
	public void addVisualization(GroupVisualization groupVisualization,
			User user) throws InsertFailedException;

	/**
	 * This method returns the actual Visualization for the group for a given User.
	 * @param userID the ID of the User
	 * @return the {@link GroupVisualization} object
	 * @throws GroupVisualizationException 
	 */
	public GroupVisualization getActualGroupVisualization(String userID) throws GroupVisualizationException;

	/**
	 * This method returns all resources which a member of the group.
	 * 
	 * @return Collection of resources of this group
	 */
	public Collection<Resource> getResources();

	/**
	 * This method returns the standard visualization of the group.
	 * 
	 * @return The standard visualization of the group
	 */
	public GroupVisualization getStandardVisualization();
	
	/**
	 * This method returns a URL of a Picture which is in the Group, if there is no Picture in the Group it returns null
	 * 
	 * @return The URL of a Picture in the Group
	 */
	public String getURLOfAPictureInGroup();
	
	/**
	 * This method returns all users of this group.
	 * 
	 * @return Collection of users of this group
	 */
	public Collection<User> getUsers();

	/**
	 * This method returns all users of this group which have a given role.
	 * 
	 * @param role
	 * @return Collection of users with the given role
	 */
	public Collection<User> getUsers(String role);
	
	/**
	 * This method returns all users, who have created or helped creating this group
	 * 
	 * @return Collection of users, who have created or helped creating this group
	 */
	public Collection<User> getCreators();
	

	/**
	 * This method returns all visualizations of the group.
	 * 
	 * @return Collection of visualizations this group has
	 */
	public Collection<GroupVisualization> getVisualizations();

	/**
	 * This method returns the visualizations a given user has for this group.
	 * 
	 * @param user
	 * @return Collection of visualizations a user has for this group
	 */
	public Collection<GroupVisualization> getVisualizations(User user);

	/**
	 * This method removes a resource from the group.
	 * 
	 * @param resource
	 * @throws DeleteFailedException
	 */
	public void removeResource(Resource resource) throws DeleteFailedException;

	/**
	 * This method removes a user from the group.
	 * 
	 * @param user
	 * @throws DeleteFailedException
	 */
	public void removeUser(User user) throws DeleteFailedException;

	/**
	 * This method removes a visualization from the group.
	 * 
	 * @param groupVisualization
	 * @param user
	 * @throws DeleteFailedException
	 */
	public void removeVisualization(GroupVisualization groupVisualization,
			User user) throws DeleteFailedException;

	/**
	 * This method sets the standard visualization of the group.
	 * 
	 * @param groupVisualization
	 */
	public void setStandardVisualization(GroupVisualization groupVisualization);
}
